home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / VGANIM10.ARJ / README.DOC < prev    next >
Text File  |  1992-08-29  |  17KB  |  592 lines
  1.                                  VGA Animate
  2.                      
  3.                               Animation Library
  4.                                  Version 1.0
  5.                        Copyright 1992, Nexus Software.
  6.  
  7.  
  8.      VGA Animate was used to create VA_DEMO.EXE.  
  9.      
  10.      VGA Animate is offered by Nexus Software as shareware, on a 
  11.      royalty-free basis.
  12.  
  13.      If you find this library useful or would like to produce
  14.      programs with graphics like VA_DEMO.EXE, order a registered
  15.      copy of the package from:
  16.  
  17.                       Nexus Software
  18.                       P.O. Box 341126
  19.                       Milwaukee, WI  53234-1126
  20.                       (414) 321-6792
  21.  
  22.      Send $39.00 for a registered copy. You'll receive:
  23.  
  24.         -- The complete library of over 100 functions, without
  25.            "guilt messages;"
  26.         -- A complete set of external fonts and a font editor;
  27.         -- A complete, cross-referenced manual;
  28.         -- A handy quick reference guide to the tools;
  29.         -- A FREE first upgrade;
  30.         -- A FREE Beta copy of our next package!
  31.  
  32.      All for only $39.00!
  33.  
  34.      Send an additional $30.00 and we will send you the complete
  35.      source code, written in C and Assembler.
  36.  
  37.      Even if you choose not to register your copy, please send any
  38.      comments, suggestions, stories of success and/or failure to
  39.      the address listed above.  We need your valuable input in
  40.      order to improve the package. 
  41.  
  42.      Please remember, we are making this package available to you
  43.      on a shareware basis - feel free to distribute copies to your
  44.      colleagues, but you may not prepare applications using these
  45.      tools without first registering your software.
  46.  
  47.  
  48. 1.  INTRODUCTION 
  49.  
  50.     VGA Animate is a graphics library which provides a complete
  51.     set of functions for accessing the undocumented VGA Animation
  52.     Mode (often referred to as "MODE X").
  53.  
  54.     This mode features:
  55.          - 320x240 Resolution
  56.          - 256 Simultaneous on-screen colors
  57.          - 3 Displayable pages
  58.          - Video storage for animation images
  59.  
  60.     The tools provided in this package allow you to perform true
  61.     animation techniques through sophisticated page swapping using
  62.     the extra pages provided. This mode is available to any standard
  63.     VGA card with 256K or more memory.
  64.  
  65.      This package is based in part on information published by
  66.      Michael Abrash in Dr. Dobb's Journal.
  67.  
  68.      For further reference, read:
  69.        --  "Mode X: 256-Color VGA Magic," Michael Abrash, 
  70.                 Dr. Dobb's Journal, July 1991;
  71.        --  "More Undocumented 256-Color VGA Magic,"  Michael Abrash, 
  72.                 Dr. Dobb's Journal, August 1991;
  73.        --  "256-Color VGA Animation," Michael Abrash, 
  74.                 Dr. Dobb's Journal, September 1991.    
  75.  
  76.     VGA Animate includes functions for PCX file support, mouse support,
  77.     sound support, and special effects.  External character fonts and
  78.     a font editor are also provided if you purchase a registered copy. 
  79.     VA_DEMO.FNT is an example of an external font file.  If a  
  80.     registered copy is purchased, many external font files are provided.
  81.  
  82.     VGA Animate supports the following C programming packages:
  83.          - Microsoft C compiler  (link VA_M.LIB into your program)
  84.          - Borland Turbo C compiler  (link VA_B.LIB into your program)
  85.          - Borland C compiler.  (link VA_B.LIB into your program)
  86.  
  87.     VGA_ANIM.H should be included in all source files that use library
  88.     functions.
  89.  
  90.     System Requirements:
  91.          - 8086 or 80X86 IBM or IBM compatible computer system.
  92.          - A standard VGA video board with minimum memory of at
  93.            least 256K.
  94.          - A VGA-compatible monitor
  95.  
  96.  
  97.  
  98. 2.  FUNCTION LISTINGS 
  99.  
  100.     The following pages describe each function in the library. These pages
  101.     contain the function prototypes and the arguments to each
  102.     function (if any).  The manual provides complete descriptions, 
  103.     examples, and a helpful cross reference for each function.
  104.  
  105.  
  106.  
  107. void adjust_mouse_click(unsigned int ticks);
  108.      unsigned int ticks     Clock ticks per click
  109.  
  110.  
  111. int arc(int x,int y,int radius,int start_deg,int end_deg,unsigned char color);
  112.      int x,int y             Arc center
  113.      int radius              Arc radius
  114.      int start_deg           Counter-clockwise start degree
  115.      int end_deg             Counter-clockwise stop degree
  116.      unsigned char color     Arc color
  117.  
  118.  
  119. long block_size(int x1,int y1,int x2,int y2);
  120.      int x1,int y1     Upper left block coordinates
  121.      int x2,int y2     Lower right block coordinates
  122.  
  123.  
  124. int circle(int x,int y,int radius,unsigned char color,char type);
  125.      int x,int y             Circle center
  126.      int radius              Circle radius
  127.      unsigned char color     Circle color
  128.      char type               FILL or EMPTY
  129.  
  130.  
  131. void cls(unsigned char color);
  132.      unsigned char color     Clear screen color
  133.  
  134.  
  135. int copy_block(char source_page,int source_x1,int source_y1,
  136.                int source_x2,int source_y2,
  137.                char dest_page,int dest_x,int dest_y);
  138.      char source_page                PAGE1, PAGE2, or PAGE3
  139.      int source_x1,int source_y1     Upper left block coordinates
  140.      int source_x2,int source_y2     Lower right block coordinates
  141.      char dest_page                  PAGE1, PAGE2, or PAGE3
  142.      int dest_x,int dest_y           Upper right block coordinates
  143.  
  144.                
  145. int copy_page(char source_page,char dest_page);
  146.      char source_page     PAGE1, PAGE2, or PAGE3
  147.      char dest_page       PAGE1, PAGE2, or PAGE3
  148.  
  149.  
  150. void default_mouse_cursor(void);
  151.  
  152.  
  153.  
  154. void delay_seconds(unsigned int seconds);
  155.      unsigned int seconds     Program pause seconds
  156.  
  157.  
  158. void delay_ticks(unsigned int ticks);
  159.      unsigned int ticks     Program pause ticks (18 ticks per second)
  160.  
  161.  
  162. void disintegrate_screen(unsigned char color,unsigned int clear_time);
  163.      unsigned char color         Disintegrate color
  164.      unsigned int clear_time     Disintegrate time in ticks
  165.  
  166.  
  167. int erase_image(IMAGE *image,char background_page,char page,int x,int y);
  168.      IMAGE *image             Image to erase
  169.      char background_page     PAGE1, PAGE2, or PAGE3
  170.      char page                PAGE1, PAGE2, or PAGE3
  171.      int x,int y              Upper left image coordinates
  172.  
  173.  
  174. void fade_screen(unsigned char fade_color,unsigned int fade_time);
  175.      unsigned char fade_color     Fade color
  176.      unsigned int fade_time       Fade time in ticks
  177.  
  178.  
  179. int fastfill(int x,int y,unsigned char color,unsigned char border);
  180.      int x,int y              coordinates of fastfill
  181.      unsigned char color      Fill color
  182.      unsigned char border     Fill border
  183.  
  184.  
  185. void free_expanded_image_space(void);
  186.  
  187.  
  188. int free_font(char font);
  189.      char font     NORMAL_FONT, SMALL_FONT, USER_FONT1 - USER_FONT5
  190.  
  191.  
  192. void free_image(IMAGE *image);
  193.      IMAGE *image     Image to free
  194.  
  195.  
  196. void free_image_space(void);
  197.  
  198.  
  199. unsigned char getcolor(int x,int y);
  200.      int x,int y     coordinates to get color at
  201.  
  202.  
  203. int getmaxx(void);
  204.  
  205.  
  206. int getmaxy(void);
  207.  
  208.  
  209.  
  210. int getx(void);
  211.  
  212.  
  213. int gety(void);
  214.  
  215.  
  216. int get_block(char page,int x1,int y1,int x2,int y2,char *block);
  217.      char page         PAGE1, PAGE2, or PAGE3
  218.      int x1,int y1     Upper left block coordinates
  219.      int x2,int y2     Lower right block coordinates
  220.      char *block       Block buffer
  221.  
  222.  
  223. unsigned int get_clock(void);
  224.  
  225.  
  226. char get_draw_page(void);
  227.  
  228.  
  229. IMAGE *get_image(char page,int source_x1,int source_y1,
  230.                  int source_x2,int source_y2);
  231.      char page                       PAGE1, PAGE2, or PAGE3
  232.      int source_x1,int source_y1     Upper left image coordinates
  233.      int source_x2,int source_y2     Lower right image coordinates
  234.  
  235.  
  236. struct mouse_coord get_left_press(void);
  237.  
  238.  
  239. struct mouse_coord get_left_release(void);
  240.  
  241.  
  242. struct mouse_coord get_middle_press(void);
  243.  
  244.  
  245. struct mouse_coord get_middle_release(void);
  246.  
  247.  
  248. struct mouse_button get_mouse_click(void);
  249.  
  250.  
  251. struct mouse_coord get_mouse_coord(void);
  252.  
  253.  
  254. struct mouse_button get_mouse_dclick(void);
  255.  
  256.  
  257. struct mouse_button get_mouse_press(void);
  258.  
  259.  
  260. struct mouse_button get_mouse_release(void);
  261.  
  262.  
  263. void get_palette(char far *palette);
  264.      char far *palette     Pointer to palette buffer
  265.  
  266.  
  267.  
  268. void get_palette_element(unsigned char color,char far *red,char
  269. far *green,char far *blue);
  270.  
  271.      unsigned char color      Color to retrieve RGB info for
  272.      char far *red            Pointer to store red level char
  273.      far *green               Pointer to store green level char
  274.      far *blue                Point to store blue level
  275.  
  276.  
  277. struct mouse_coord get_right_press(void);
  278.  
  279.  
  280. struct mouse_coord get_right_release(void);
  281.  
  282.  
  283. struct text_settings get_text_settings(void);
  284.  
  285.  
  286. int get_transparent_color(void);
  287.  
  288.  
  289. int get_video_error(void);
  290.  
  291.  
  292. void hide_mouse(void);
  293.  
  294.  
  295. unsigned int image_size(int source_x1,int source_y1,
  296.                         int source_x2,int source_y2);
  297.      int source_x1,int source_y1     Upper left image coordinates
  298.      int source_x2,int source_y2     Lower right image coordinates
  299.  
  300.  
  301. unsigned int image_space_left(void);
  302.  
  303.  
  304. char init_mouse(void);
  305.  
  306.  
  307. char is_font_loaded(char font);
  308.      char font     NORMAL_FONT, SMALL_FONT, USER_FONT1 - USER_FONT5
  309.  
  310.  
  311. char is_mouse_click(void);
  312.  
  313.  
  314. char is_mouse_dclick(void);
  315.  
  316.  
  317. char is_mouse_press(void);
  318.  
  319.  
  320. char is_mouse_release(void);
  321.  
  322.  
  323. char is_mouse_visible(void);
  324.  
  325.  
  326.  
  327. char is_valid_coord(int x,int y);
  328.      int x,int y     coordinates to test
  329.  
  330.  
  331. int line(int x1,int y1,int x2,int y2,unsigned char color);
  332.      int x1,int y1           Line coordinates 1
  333.      int x2,int y2           Line coordinates 2
  334.      unsigned char color     Line color
  335.  
  336.  
  337. int linerel(int x_offset,int y_offset,unsigned char color);
  338.      int x_offset,int y_offset     Offset to draw line
  339.      unsigned char color           Line color
  340.  
  341.  
  342. int lineto(int x,int y,unsigned char color);
  343.      int x,int y             coordinates to draw line to
  344.      unsigned char color     Line color
  345.  
  346.  
  347. int load_block(char page,int x,int y,char *filename);
  348.      char page               PAGE1, PAGE2, or PAGE3
  349.      int x, int y            Upper left block coordinates
  350.      char *filename          Block filename
  351.  
  352.  
  353. int load_font(char font,char *fontfile);
  354.      char font          USER_FONT1 - USER_FONT5
  355.      char *fontfile     External font file
  356.  
  357.  
  358. int load_palette(char *filename);
  359.      char *filename     Palette file
  360.  
  361.  
  362. int load_pcx_screen(char page,char *filename,char load_palette);
  363.      char page             PAGE1, PAGE2, or PAGE3
  364.      char *filename        256 color PCX file
  365.      char load_palette     TRUE or FALSE
  366.  
  367.  
  368. int load_screen(char page,char *filename);
  369.      char page          PAGE1, PAGE2, or PAGE3
  370.      char *filename     Screen file
  371.  
  372.  
  373. int moverel(int x_offset,int y_offset);
  374.      int x_offset,int y_offset     Offset to move
  375.  
  376.  
  377. int moveto(int x,int y);
  378.      int x,int y     coordinates to move to 
  379.  
  380.  
  381.  
  382. void move_block(char page, int source_x1,int source_y1,
  383.                 int source_x2,int source_y2,int dest_x,int dest_y);
  384.      char page                       PAGE1, PAGE2, or PAGE3
  385.      int source_x1,int source_y1     Upper left block coordinates
  386.      int source_x2,int source_y2     Lower right block coordinates
  387.      int dest_x,int dest_y           Upper left block coordinates
  388.  
  389.  
  390. int paint(int x,int y,unsigned char color,unsigned char border);
  391.      int x,int y              Paint coordinates
  392.      unsigned char color      Paint color
  393.      unsigned char border     Paint border
  394.  
  395.  
  396. void play_sound(unsigned int freq,unsigned int duration);
  397.      unsigned int freq         Sound frequency
  398.      unsigned int duration     Sound duration in ticks
  399.  
  400.  
  401. int point(int x,int y,unsigned char color);
  402.      int x,int y             Point coordinates
  403.      unsigned char color     Point color
  404.  
  405.  
  406. int print_text(int x,int y,char *text);
  407.      int x,int y     Text coordinates
  408.      char *text      Text to print
  409.  
  410.  
  411. int put_block(char page,int x,int y,char *block);
  412.      char page       PAGE1, PAGE2, or PAGE3
  413.      int x,int y     Block coordinates
  414.      char *block     Block buffer
  415.  
  416.  
  417. int put_image(IMAGE *image,char page,int dest_x,int dest_y);
  418.      IMAGE *image              Image to draw
  419.      char page                 PAGE1, PAGE2, or PAGE3
  420.      int dest_x,int dest_y     Upper left image coordinates
  421.  
  422.  
  423. int rectangle(int x1,int y1,int x2,int y2,unsigned char color,char type);
  424.      int x1,int y1           Upper left rectangle coordinates
  425.      int x2,int y2           Lower right rectangle coordinates
  426.      unsigned char color     Rectangle color
  427.      char type               EMPTY or FILL
  428.  
  429.  
  430. void reset_mouse(void);
  431.  
  432.  
  433. int save_block(char page,int x1,int y1,int x2,int y2,char *filename);
  434.      char page          PAGE1, PAGE2, or PAGE3
  435.      int x1,int y1      Upper left block coordinates
  436.      int x2,int y2      Lower right block coordinates
  437.      char *filename     Block file
  438.  
  439.  
  440.  
  441. int save_palette(char *filename);
  442.      char *filename     Palette file
  443.  
  444.  
  445. int save_pcx_screen(char page,char *filename);
  446.      char page          PAGE1, PAGE2, or PAGE3
  447.      char *filename     PCX file
  448.  
  449.  
  450. int save_screen(char page,char *filename);
  451.      char page          PAGE1, PAGE2, or PAGE3
  452.      char *filename     Screen file
  453.  
  454.  
  455. int set_current_font(char font);
  456.      char font     NORMAL_FONT, SMALL_FONT, USER_FONT1 - USER_FONT5
  457.  
  458.  
  459. int set_draw_page(char page);
  460.      char page     PAGE1, PAGE2, or PAGE3
  461.  
  462.  
  463. void set_mouse_cursor(char *cursor,char *mask);
  464.      char *cursor    Cursor definition array
  465.      char *mask      Mask definition array
  466.  
  467.  
  468. int set_mouse_page(char page);
  469.      char page       PAGE1, PAGE2, or PAGE3
  470.  
  471.  
  472. int set_mouse_pos(int x,int y);
  473.      int x,int y     Mouse coordinates
  474.  
  475.  
  476. void set_palette(char far *palette, char speed);
  477.      char far *palette     Palette buffer
  478.      char speed            SLOW_PAL or FAST_PAL
  479.  
  480.  
  481. void set_palette_element(unsigned char color,char red,char
  482. green,char blue);
  483.      unsigned char color     Color index
  484.      char red                Red intensity
  485.      char green              Green intensity
  486.      char blue               Blue intensity
  487.  
  488.  
  489. int set_text_alignment(char alignment);
  490.      char alignment     TOP_ALIGNMENT, BOTTOM_ALIGNMENT, BASELINE_ALIGNMENT
  491.  
  492.  
  493. void set_text_bgcolor(unsigned char bg_color);
  494.      unsigned char bg_color     Background color
  495.  
  496.  
  497.  
  498. void set_text_color(unsigned char fg_color,unsigned char bg_color);
  499.      unsigned char fg_color     Foreground color
  500.      unsigned char bg_color     Background color
  501.  
  502.  
  503. int set_text_direction(char direction);
  504.      char direction     LEFT_RIGHT, UP_DOWN 
  505.  
  506.  
  507. void set_text_fgcolor(unsigned char fg_color);
  508.      unsigned char fg_color     Foreground color
  509.  
  510.  
  511. void set_text_bgcolor(unsigned char bg_color);
  512.      unsigned char bg_color     Background color
  513.  
  514.  
  515. void set_text_color(unsigned char fg_color,unsigned char bg_color);
  516.      unsigned char fg_color     Foreground color
  517.      unsigned char bg_color     Background color
  518.  
  519.  
  520. int set_text_direction(char direction);
  521.      char direction     LEFT_RIGHT, UP_DOWN 
  522.  
  523.  
  524. void set_text_fgcolor(unsigned char fg_color);
  525.      unsigned char fg_color     For;
  526.      int x,int y                    Text coordinates
  527.      char *text                     Text to print
  528.      int x_offset,int y_offset      Offset of shadow
  529.      unsigned char shadow_color     Shadow color
  530.  
  531.  
  532. void show_mouse(void);
  533.  
  534.  
  535. void show_page(char page);
  536.      char page     PAGE1, PAGE2, or PAGE3
  537.  
  538.  
  539. void shrink_screen(unsigned char color,
  540.                    unsigned int xshrink,unsigned int yshrink);
  541.      unsigned char color      Replacement color
  542.      unsigned int xshrink     Horizontal reduction factor
  543.      unsigned int yshrink     Vertical reduction factor
  544.  
  545.  
  546. void sound_off(void);
  547.  
  548.  
  549. void sound_on(unsigned int freq);
  550.      unsigned int freq     Frequency of sound
  551.  
  552.  
  553.  
  554. void text_mode(void);
  555.  
  556.  
  557. int text_baseline(void);
  558.  
  559.  
  560. int text_char(int x,int y,unsigned char ch);
  561.      int x,int y          Text coordinates
  562.      unsigned char ch     Character to print
  563.  
  564.  
  565. unsigned char text_end_char(void);
  566.  
  567.  
  568. int text_height(void);
  569.  
  570.  
  571. unsigned char text_start_char(void);
  572.  
  573.  
  574. int text_width(void);
  575.  
  576.  
  577. void transparent_on(void);
  578.  
  579.  
  580. void transparent_off(void);
  581.  
  582.  
  583. char *video_error_msg(int error);
  584.      int error     Error number
  585.  
  586.  
  587. void video_mode(void); 
  588.  
  589.  
  590. MICROSOFT is a registered trademark of Microsoft Corporation.
  591. BORLAND is a registered trademark of Borland International.
  592.